<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html 
     PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
  <title>Module: ActionController::Streaming</title>
  <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
  <meta http-equiv="Content-Script-Type" content="text/javascript" />
  <link rel="stylesheet" href="../.././rdoc-style.css" type="text/css" media="screen" />
  <script type="text/javascript">
  // <![CDATA[

  function popupCode( url ) {
    window.open(url, "Code", "resizable=yes,scrollbars=yes,toolbar=no,status=no,height=150,width=400")
  }

  function toggleCode( id ) {
    if ( document.getElementById )
      elem = document.getElementById( id );
    else if ( document.all )
      elem = eval( "document.all." + id );
    else
      return false;

    elemStyle = elem.style;
    
    if ( elemStyle.display != "block" ) {
      elemStyle.display = "block"
    } else {
      elemStyle.display = "none"
    }

    return true;
  }
  
  // Make codeblocks hidden by default
  document.writeln( "<style type=\"text/css\">div.method-source-code { display: none }</style>" )
  
  // ]]>
  </script>

</head>
<body>



    <div id="classHeader">
        <table class="header-table">
        <tr class="top-aligned-row">
          <td><strong>Module</strong></td>
          <td class="class-name-in-header">ActionController::Streaming</td>
        </tr>
        <tr class="top-aligned-row">
            <td><strong>In:</strong></td>
            <td>
                <a href="../../files/vendor/rails/actionpack/lib/action_controller/streaming_rb.html">
                vendor/rails/actionpack/lib/action_controller/streaming.rb
                </a>
        <br />
            </td>
        </tr>

        </table>
    </div>
  <!-- banner header -->

  <div id="bodyContent">



  <div id="contextContent">

    <div id="description">
      <p>
Methods for sending files and streams to the browser instead of rendering.
</p>

    </div>


   </div>

    <div id="method-list">
      <h3 class="section-bar">Methods</h3>

      <div class="name-list">
      <a href="#M000229">send_data</a>&nbsp;&nbsp;
      <a href="#M000228">send_file</a>&nbsp;&nbsp;
      </div>
    </div>

  </div>


    <!-- if includes -->

    <div id="section">


    <div id="constants-list">
      <h3 class="section-bar">Constants</h3>

      <div class="name-list">
        <table summary="Constants">
        <tr class="top-aligned-row context-row">
          <td class="context-item-name">DEFAULT_SEND_FILE_OPTIONS</td>
          <td>=</td>
          <td class="context-item-value">{       :type         =&gt; 'application/octet-stream'.freeze,       :disposition  =&gt; 'attachment'.freeze,       :stream       =&gt; true,        :buffer_size  =&gt; 4096</td>
        </tr>
        </table>
      </div>
    </div>



      


    <!-- if method_list -->
    <div id="methods">
      <h3 class="section-bar">Protected Instance methods</h3>

      <div id="method-M000229" class="method-detail">
        <a name="M000229"></a>

        <div class="method-heading">
          <a href="#M000229" class="method-signature">
          <span class="method-name">send_data</span><span class="method-args">(data, options = {})</span>
          </a>
        </div>
      
        <div class="method-description">
          <p>
Send binary data to the user as a file download. May set content type,
apparent file name, and specify whether to show data inline or download as
an attachment.
</p>
<p>
Options:
</p>
<ul>
<li><tt>:filename</tt> - Suggests a filename for the browser to use.

</li>
<li><tt>:type</tt> - specifies an HTTP content type. Defaults to
&#8216;application/octet-stream&#8217;.

</li>
<li><tt>:disposition</tt> - specifies whether the file will be shown inline or
downloaded. Valid values are &#8216;inline&#8217; and
&#8216;attachment&#8217; (default).

</li>
<li><tt>:status</tt> - specifies the status code to send with the response.
Defaults to &#8216;200 OK&#8217;.

</li>
</ul>
<p>
Generic data download:
</p>
<pre>
  send_data buffer
</pre>
<p>
Download a dynamically-generated tarball:
</p>
<pre>
  send_data generate_tgz('dir'), :filename =&gt; 'dir.tgz'
</pre>
<p>
Display an image Active Record in the browser:
</p>
<pre>
  send_data image.data, :type =&gt; image.content_type, :disposition =&gt; 'inline'
</pre>
<p>
See <tt><a href="Streaming.html#M000228">send_file</a></tt> for more
information on HTTP Content-* headers and caching.
</p>
          <p><a class="source-toggle" href="#"
            onclick="toggleCode('M000229-source');return false;">[Source]</a></p>
          <div class="method-source-code" id="M000229-source">
<pre>
     <span class="ruby-comment cmt"># File vendor/rails/actionpack/lib/action_controller/streaming.rb, line 107</span>
107:       <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">send_data</span>(<span class="ruby-identifier">data</span>, <span class="ruby-identifier">options</span> = {}) <span class="ruby-comment cmt">#:doc:</span>
108:         <span class="ruby-identifier">logger</span>.<span class="ruby-identifier">info</span> <span class="ruby-node">&quot;Sending data #{options[:filename]}&quot;</span> <span class="ruby-keyword kw">unless</span> <span class="ruby-identifier">logger</span>.<span class="ruby-identifier">nil?</span>
109:         <span class="ruby-identifier">send_file_headers!</span> <span class="ruby-identifier">options</span>.<span class="ruby-identifier">merge</span>(<span class="ruby-identifier">:length</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-identifier">data</span>.<span class="ruby-identifier">size</span>)
110:         <span class="ruby-ivar">@performed_render</span> = <span class="ruby-keyword kw">false</span>
111:         <span class="ruby-identifier">render</span> <span class="ruby-identifier">:status</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-identifier">options</span>[<span class="ruby-identifier">:status</span>], <span class="ruby-identifier">:text</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-identifier">data</span>
112:       <span class="ruby-keyword kw">end</span>
</pre>
          </div>
        </div>
      </div>

      <div id="method-M000228" class="method-detail">
        <a name="M000228"></a>

        <div class="method-heading">
          <a href="#M000228" class="method-signature">
          <span class="method-name">send_file</span><span class="method-args">(path, options = {})</span>
          </a>
        </div>
      
        <div class="method-description">
          <p>
Sends the file by streaming it 4096 bytes at a time. This way the whole
file doesn&#8216;t need to be read into memory at once. This makes it
feasible to send even large files.
</p>
<p>
Be careful to sanitize the path parameter if it coming from a web page. <a
href="Streaming.html#M000228">send_file</a>(params[:path]) allows a
malicious user to download any file on your server.
</p>
<p>
Options:
</p>
<ul>
<li><tt>:filename</tt> - suggests a filename for the browser to use. Defaults
to File.basename(path).

</li>
<li><tt>:type</tt> - specifies an HTTP content type. Defaults to
&#8216;application/octet-stream&#8217;.

</li>
<li><tt>:disposition</tt> - specifies whether the file will be shown inline or
downloaded. Valid values are &#8216;inline&#8217; and
&#8216;attachment&#8217; (default).

</li>
<li><tt>:stream</tt> - whether to send the file to the user agent as it is read
(true) or to read the entire file before sending (false). Defaults to true.

</li>
<li><tt>:buffer_size</tt> - specifies size (in bytes) of the buffer used to
stream the file. Defaults to 4096.

</li>
<li><tt>:status</tt> - specifies the status code to send with the response.
Defaults to &#8216;200 OK&#8217;.

</li>
<li><tt>:url_based_filename</tt> - set to true if you want the browser guess
the filename from the URL, which is necessary for i18n filenames on certain
browsers (setting :filename overrides this option).

</li>
</ul>
<p>
The default Content-Type and Content-Disposition headers are set to
download arbitrary binary files in as many browsers as possible. IE
versions 4, 5, 5.5, and 6 are all known to have a variety of quirks
(especially when downloading over SSL).
</p>
<p>
Simple download:
</p>
<pre>
  send_file '/path/to.zip'
</pre>
<p>
Show a JPEG in the browser:
</p>
<pre>
  send_file '/path/to.jpeg', :type =&gt; 'image/jpeg', :disposition =&gt; 'inline'
</pre>
<p>
Show a 404 page in the browser:
</p>
<pre>
  send_file '/path/to/404.html', :type =&gt; 'text/html; charset=utf-8', :status =&gt; 404
</pre>
<p>
Read about the other Content-* HTTP headers if you&#8216;d like to provide
the user with more information (such as Content-Description). <a
href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.11">www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.11</a>
</p>
<p>
Also be aware that the document may be cached by proxies and browsers. The
Pragma and Cache-Control headers declare how the file may be cached by
intermediaries. They default to require clients to validate with the server
before releasing cached responses. See <a
href="http://www.mnot.net/cache_docs">www.mnot.net/cache_docs</a>/ for an
overview of web caching and <a
href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.9">www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.9</a>
for the Cache-Control header spec.
</p>
          <p><a class="source-toggle" href="#"
            onclick="toggleCode('M000228-source');return false;">[Source]</a></p>
          <div class="method-source-code" id="M000228-source">
<pre>
    <span class="ruby-comment cmt"># File vendor/rails/actionpack/lib/action_controller/streaming.rb, line 61</span>
61:       <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">send_file</span>(<span class="ruby-identifier">path</span>, <span class="ruby-identifier">options</span> = {}) <span class="ruby-comment cmt">#:doc:</span>
62:         <span class="ruby-identifier">raise</span> <span class="ruby-constant">MissingFile</span>, <span class="ruby-node">&quot;Cannot read file #{path}&quot;</span> <span class="ruby-keyword kw">unless</span> <span class="ruby-constant">File</span>.<span class="ruby-identifier">file?</span>(<span class="ruby-identifier">path</span>) <span class="ruby-keyword kw">and</span> <span class="ruby-constant">File</span>.<span class="ruby-identifier">readable?</span>(<span class="ruby-identifier">path</span>)
63: 
64:         <span class="ruby-identifier">options</span>[<span class="ruby-identifier">:length</span>]   <span class="ruby-operator">||=</span> <span class="ruby-constant">File</span>.<span class="ruby-identifier">size</span>(<span class="ruby-identifier">path</span>)
65:         <span class="ruby-identifier">options</span>[<span class="ruby-identifier">:filename</span>] <span class="ruby-operator">||=</span> <span class="ruby-constant">File</span>.<span class="ruby-identifier">basename</span>(<span class="ruby-identifier">path</span>) <span class="ruby-keyword kw">unless</span> <span class="ruby-identifier">options</span>[<span class="ruby-identifier">:url_based_filename</span>]
66:         <span class="ruby-identifier">send_file_headers!</span> <span class="ruby-identifier">options</span>
67: 
68:         <span class="ruby-ivar">@performed_render</span> = <span class="ruby-keyword kw">false</span>
69: 
70:         <span class="ruby-keyword kw">if</span> <span class="ruby-identifier">options</span>[<span class="ruby-identifier">:stream</span>]
71:           <span class="ruby-identifier">render</span> <span class="ruby-identifier">:status</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-identifier">options</span>[<span class="ruby-identifier">:status</span>], <span class="ruby-identifier">:text</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-constant">Proc</span>.<span class="ruby-identifier">new</span> { <span class="ruby-operator">|</span><span class="ruby-identifier">response</span>, <span class="ruby-identifier">output</span><span class="ruby-operator">|</span>
72:             <span class="ruby-identifier">logger</span>.<span class="ruby-identifier">info</span> <span class="ruby-node">&quot;Streaming file #{path}&quot;</span> <span class="ruby-keyword kw">unless</span> <span class="ruby-identifier">logger</span>.<span class="ruby-identifier">nil?</span>
73:             <span class="ruby-identifier">len</span> = <span class="ruby-identifier">options</span>[<span class="ruby-identifier">:buffer_size</span>] <span class="ruby-operator">||</span> <span class="ruby-value">4096</span>
74:             <span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-identifier">path</span>, <span class="ruby-value str">'rb'</span>) <span class="ruby-keyword kw">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">file</span><span class="ruby-operator">|</span>
75:               <span class="ruby-keyword kw">while</span> <span class="ruby-identifier">buf</span> = <span class="ruby-identifier">file</span>.<span class="ruby-identifier">read</span>(<span class="ruby-identifier">len</span>)
76:                 <span class="ruby-identifier">output</span>.<span class="ruby-identifier">write</span>(<span class="ruby-identifier">buf</span>)
77:               <span class="ruby-keyword kw">end</span>
78:             <span class="ruby-keyword kw">end</span>
79:           }
80:         <span class="ruby-keyword kw">else</span>
81:           <span class="ruby-identifier">logger</span>.<span class="ruby-identifier">info</span> <span class="ruby-node">&quot;Sending file #{path}&quot;</span> <span class="ruby-keyword kw">unless</span> <span class="ruby-identifier">logger</span>.<span class="ruby-identifier">nil?</span>
82:           <span class="ruby-constant">File</span>.<span class="ruby-identifier">open</span>(<span class="ruby-identifier">path</span>, <span class="ruby-value str">'rb'</span>) { <span class="ruby-operator">|</span><span class="ruby-identifier">file</span><span class="ruby-operator">|</span> <span class="ruby-identifier">render</span> <span class="ruby-identifier">:status</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-identifier">options</span>[<span class="ruby-identifier">:status</span>], <span class="ruby-identifier">:text</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-identifier">file</span>.<span class="ruby-identifier">read</span> }
83:         <span class="ruby-keyword kw">end</span>
84:       <span class="ruby-keyword kw">end</span>
</pre>
          </div>
        </div>
      </div>


    </div>


  </div>


<div id="validator-badges">
  <p><small><a href="http://validator.w3.org/check/referer">[Validate]</a></small></p>
</div>

</body>
</html>